home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / man.3 / Async.3 < prev    next >
Text File  |  1995-07-17  |  11KB  |  354 lines
  1. '\"
  2. '\" Copyright (c) 1989-1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/tcl/man/RCS/Async.3,v 1.5 93/09/17 15:21:50 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .\" The definitions below are for supplemental macros used in Tcl/Tk
  24. .\" manual entries.
  25. .\"
  26. .\" .HS name section [date [version]]
  27. .\"    Replacement for .TH in other man pages.  See below for valid
  28. .\"    section names.
  29. .\"
  30. .\" .AP type name in/out [indent]
  31. .\"    Start paragraph describing an argument to a library procedure.
  32. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  33. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  34. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  35. .\"    needed;  use .AS below instead)
  36. .\"
  37. .\" .AS [type [name]]
  38. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  39. .\"    name are examples of largest possible arguments that will be passed
  40. .\"    to .AP later.  If args are omitted, default tab stops are used.
  41. .\"
  42. .\" .BS
  43. .\"    Start box enclosure.  From here until next .BE, everything will be
  44. .\"    enclosed in one large box.
  45. .\"
  46. .\" .BE
  47. .\"    End of box enclosure.
  48. .\"
  49. .\" .VS
  50. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  51. .\"    of man pages.
  52. .\"
  53. .\" .VE
  54. .\"    End of vertical sidebar.
  55. .\"
  56. .\" .DS
  57. .\"    Begin an indented unfilled display.
  58. .\"
  59. .\" .DE
  60. .\"    End of indented unfilled display.
  61. .\"
  62. '\"    # Heading for Tcl/Tk man pages
  63. .de HS
  64. .ds ^3 \\0
  65. .if !"\\$3"" .ds ^3 \\$3
  66. .if '\\$2'cmds'       .TH \\$1 1 \\*(^3 \\$4
  67. .if '\\$2'lib'        .TH \\$1 3 \\*(^3 \\$4
  68. .if '\\$2'tcl'        .TH \\$1 n \\*(^3 Tcl "Tcl Built-In Commands"
  69. .if '\\$2'tk'         .TH \\$1 n \\*(^3 Tk "Tk Commands"
  70. .if '\\$2'tclc'        .TH \\$1 3 \\*(^3 Tcl "Tcl Library Procedures"
  71. .if '\\$2'tkc'         .TH \\$1 3 \\*(^3 Tk "Tk Library Procedures"
  72. .if '\\$2'tclcmds'         .TH \\$1 1 \\*(^3 Tk "Tcl Applications"
  73. .if '\\$2'tkcmds'         .TH \\$1 1 \\*(^3 Tk "Tk Applications"
  74. .if t .wh -1.3i ^B
  75. .nr ^l \\n(.l
  76. .ad b
  77. ..
  78. '\"    # Start an argument description
  79. .de AP
  80. .ie !"\\$4"" .TP \\$4
  81. .el \{\
  82. .   ie !"\\$2"" .TP \\n()Cu
  83. .   el          .TP 15
  84. .\}
  85. .ie !"\\$3"" \{\
  86. .ta \\n()Au \\n()Bu
  87. \&\\$1    \\fI\\$2\\fP    (\\$3)
  88. .\".b
  89. .\}
  90. .el \{\
  91. .br
  92. .ie !"\\$2"" \{\
  93. \&\\$1    \\fI\\$2\\fP
  94. .\}
  95. .el \{\
  96. \&\\fI\\$1\\fP
  97. .\}
  98. .\}
  99. ..
  100. '\"    # define tabbing values for .AP
  101. .de AS
  102. .nr )A 10n
  103. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  104. .nr )B \\n()Au+15n
  105. .\"
  106. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  107. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  108. ..
  109. '\"    # BS - start boxed text
  110. '\"    # ^y = starting y location
  111. '\"    # ^b = 1
  112. .de BS
  113. .br
  114. .mk ^y
  115. .nr ^b 1u
  116. .if n .nf
  117. .if n .ti 0
  118. .if n \l'\\n(.lu\(ul'
  119. .if n .fi
  120. ..
  121. '\"    # BE - end boxed text (draw box now)
  122. .de BE
  123. .nf
  124. .ti 0
  125. .mk ^t
  126. .ie n \l'\\n(^lu\(ul'
  127. .el \{\
  128. .\"    Draw four-sided box normally, but don't draw top of
  129. .\"    box if the box started on an earlier page.
  130. .ie !\\n(^b-1 \{\
  131. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  132. .\}
  133. .el \}\
  134. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  135. .\}
  136. .\}
  137. .fi
  138. .br
  139. .nr ^b 0
  140. ..
  141. '\"    # VS - start vertical sidebar
  142. '\"    # ^Y = starting y location
  143. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  144. .de VS
  145. .mk ^Y
  146. .ie n 'mc \s12\(br\s0
  147. .el .nr ^v 1u
  148. ..
  149. '\"    # VE - end of vertical sidebar
  150. .de VE
  151. .ie n 'mc
  152. .el \{\
  153. .ev 2
  154. .nf
  155. .ti 0
  156. .mk ^t
  157. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  158. .sp -1
  159. .fi
  160. .ev
  161. .\}
  162. .nr ^v 0
  163. ..
  164. '\"    # Special macro to handle page bottom:  finish off current
  165. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  166. '\"    # page bottom macro.
  167. .de ^B
  168. .ev 2
  169. 'ti 0
  170. 'nf
  171. .mk ^t
  172. .if \\n(^b \{\
  173. .\"    Draw three-sided box if this is the box's first page,
  174. .\"    draw two sides but no top otherwise.
  175. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  176. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  177. .\}
  178. .if \\n(^v \{\
  179. .nr ^x \\n(^tu+1v-\\n(^Yu
  180. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  181. .\}
  182. .bp
  183. 'fi
  184. .ev
  185. .if \\n(^b \{\
  186. .mk ^y
  187. .nr ^b 2
  188. .\}
  189. .if \\n(^v \{\
  190. .mk ^Y
  191. .\}
  192. ..
  193. '\"    # DS - begin display
  194. .de DS
  195. .RS
  196. .nf
  197. .sp
  198. ..
  199. '\"    # DE - end display
  200. .de DE
  201. .fi
  202. .RE
  203. .sp .5
  204. ..
  205. .HS Tcl_AsyncCreate tclc 7.0
  206. .BS
  207. .SH NAME
  208. Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncInvoke, Tcl_AsyncDelete \- handle asynchronous events
  209. .SH SYNOPSIS
  210. .nf
  211. \fB#include <tcl.h>\fR
  212. .sp
  213. extern int \fBtcl_AsyncReady\fR;
  214. .sp
  215. Tcl_AsyncHandler
  216. \fBTcl_AsyncCreate\fR(\fIproc, clientData\fR)
  217. .sp
  218. \fBTcl_AsyncMark\fR(\fIasync\fR)
  219. .sp
  220. int
  221. \fBTcl_AsyncInvoke\fR(\fIinterp, code\fR)
  222. .sp
  223. \fBTcl_AsyncDelete\fR(\fIasync\fR)
  224. .SH ARGUMENTS
  225. .AS Tcl_AsyncHandler clientData
  226. .AP Tcl_AsyncProc *proc in
  227. Procedure to invoke to handle an asynchronous event.
  228. .AP ClientData clientData in
  229. One-word value to pass to \fIproc\fR.
  230. .AP Tcl_AsyncHandler async in
  231. Token for asynchronous event handler.
  232. .AP Tcl_Interp *interp in
  233. Tcl interpreter in which command was being evaluated when handler was
  234. invoked, or NULL if handler was invoked when there was no interpreter
  235. active.
  236. .AP int code in
  237. Completion code from command that just completed in \fIinterp\fR,
  238. or 0 if \fIinterp\fR is NULL.
  239. .BE
  240.  
  241. .SH DESCRIPTION
  242. .PP
  243. These procedures provide a safe mechanism for dealing with
  244. asynchronous events such as signals.
  245. If an event such as a signal occurs while a Tcl script is being
  246. evaluated then it isn't safe to take any substantive action to
  247. process the event.
  248. For example, it isn't safe to evaluate a Tcl script since the
  249. intepreter may already be in the middle of evaluating a script;
  250. it may not even be safe to allocate memory, since a memory
  251. allocation could have been in progress when the event occurred.
  252. The only safe approach is to set a flag indicating that the event
  253. occurred, then handle the event later when the world has returned
  254. to a clean state, such as after the current Tcl command completes.
  255. .PP
  256. \fBTcl_AsyncCreate\fR creates an asynchronous handler and returns
  257. a token for it.
  258. The asynchronous handler must be created before
  259. any occurrences of the asynchronous event that it is intended
  260. to handle (it is not safe to create a handler at the time of
  261. an event).
  262. When an asynchronous event occurs the code that detects the event
  263. (such as a signal handler) should call \fBTcl_AsyncMark\fR with the
  264. token for the handler.
  265. \fBTcl_AsyncMark\fR will mark the handler as ready to execute, but it
  266. will not invoke the handler immediately.
  267. Tcl will call the \fIproc\fR associated with the handler later, when
  268. the world is in a safe state, and \fIproc\fR can then carry out
  269. the actions associated with the asynchronous event.
  270. \fIProc\fR should have arguments and result that match the
  271. type \fBTcl_AsyncProc\fR:
  272. .nf
  273. .RS
  274. typedef int Tcl_AsyncProc(
  275. .RS
  276. ClientData \fIclientData\fR,
  277. Tcl_Interp *\fIinterp\fR,
  278. int \fIcode\fR);
  279. .RE
  280. .RE
  281. .fi
  282. The \fIclientData\fR will be the same as the \fIclientData\fR
  283. argument passed to \fBTcl_AsyncCreate\fR when the handler was
  284. created.
  285. If \fIproc\fR is invoked just after a command has completed
  286. execution in an interpreter, then \fIinterp\fR will identify
  287. the interpreter in which the command was evaluated and
  288. \fIcode\fR will be the completion code returned by that
  289. command.
  290. The command's result will be present in \fIinterp->result\fR.
  291. When \fIproc\fR returns, whatever it leaves in \fIinterp->result\fR
  292. will be returned as the result of the command and the integer
  293. value returned by \fIproc\fR will be used as the new completion
  294. code for the command.
  295. .PP
  296. It is also possible for \fIproc\fR to be invoked when no interpreter
  297. is active.
  298. This can happen, for example, if an asynchronous event occurs while
  299. the application is waiting for interactive input or an X event.
  300. In this case \fIinterp\fR will be NULL and \fIcode\fR will be
  301. 0, and the return value from \fIproc\fR will be ignored.
  302. .PP
  303. The procedure \fBTcl_AsyncInvoke\fR is called to invoke all of the
  304. handlers that are ready.
  305. The global variable \fBtcl_AsyncReady\fR will be non-zero whenever any
  306. asynchronous handlers are ready;  it can be checked to avoid calls
  307. to \fBTcl_AsyncInvoke\fR when there are no ready handlers.
  308. Tcl checks \fBtcl_AsyncReady\fR after each command is evaluated
  309. and calls \fBTcl_AsyncInvoke\fR if needed.
  310. Applications may also call \fBTcl_AsyncInvoke\fR at interesting
  311. times for that application.
  312. For example, Tk's event handler checks \fBtcl_AsyncReady\fR
  313. after each event and calls \fBTcl_AsyncInvoke\fR if needed.
  314. The \fIinterp\fR and \fIcode\fR arguments to \fBTcl_AsyncInvoke\fR
  315. have the same meaning as for \fIproc\fR:  they identify the active
  316. intepreter, if any, and the completion code from the command
  317. that just completed.
  318. .PP
  319. \fBTcl_AsyncDelete\fR removes an asynchronous handler so that
  320. its \fIproc\fR will never be invoked again.
  321. A handler can be deleted even when ready, and it will still
  322. not be invoked.
  323. .PP
  324. If multiple handlers become active at the same time, the
  325. handlers are invoked in the order they were created (oldest
  326. handler first).
  327. The \fIcode\fR and \fIinterp->result\fR for later handlers
  328. reflect the values returned by earlier handlers, so that
  329. the most recently created handler has last say about
  330. the interpreter's result and completion code.
  331. If new handlers become ready while handlers are executing,
  332. \fBTcl_AsyncInvoke\fR will invoke them all;  at each point it
  333. invokes the highest-priority (oldest) ready handler, repeating
  334. this over and over until there are no longer any ready handlers.
  335.  
  336. .SH WARNING
  337. .PP
  338. It is almost always a bad idea for an asynchronous event
  339. handler to modify \fIinterp->result\fR or return a code different
  340. from its \fIcode\fR argument.
  341. This sort of behavior can disrupt the execution of scripts in
  342. subtle ways and result in bugs that are extremely difficult
  343. to track down.
  344. If an asynchronous event handler needs to evaluate Tcl scripts
  345. then it should first save \fIinterp->result\fR plus the values
  346. of the variables \fBerrorInfo\fR and \fBerrorCode\fR (this can
  347. be done, for example, by storing them in dynamic strings).
  348. When the asynchronous handler is finished it should restore
  349. \fIinterp->result\fR, \fBerrorInfo\fR, and \fBerrorCode\fR,
  350. and return the \fIcode\fR argument.
  351.  
  352. .SH KEYWORDS
  353. asynchronous event, handler, signal
  354.